Skip to main content

OpenAPI Spec Enhancement

#OpenAPI Spec Enhancement

In the first step of the generation process, ThorAPI enhances your spec with a variety of features:

  • CRUD Rest Endpoints for POST/PUT/GET/DELETE for each Schema Component (Model Object) in the api.yaml spec input file.

  • Detailed and enhanced Schema Components (Model Objects) in the api.hbs.yaml spec input file.

  • These 2 fully customizable spec templates are merged and enhanced with mandatory "metadata" fields for every object (lastModifiedById, keyHash, createDate, etc.).

Use ThorAPI to process and merge your OpenAPI templates.

Input files:

  • src/main/resources/openapi/api.yaml: Your base OpenAPI specification.
  • src/main/resources/openapi/api.hbs.yaml: The ThorAPI Handlebars template.

Command:

java -jar lib/generator-<valkyrai_version>-exec.jar \
  src/main/resources/openapi/api.yaml \
  src/main/resources/openapi/output-api.yaml \
  src/main/resources/openapi/api

ThorAPI leverages existing tools like Maven and OpenAPITools CodeGen, Handlebars templating, Spring, JPA, REST APIs, TypeScript, and Java.

Enhance OpenAPI Spec

Run the ThorAPI to process the 2 OpenAPI templates.

The 2 templates are merged and enhanced with the special ThorAPI fields -- with the api.yaml determining which model objects will have REST endpoints generated.

> src/main/resources/openapi/api.yaml
> src/main/resources/openapi/api.hbs.yaml
/usr/bin/env java -jar lib/generator-<valkyrai_version>-exec.jar src/main/resources/openapi/api.yaml src/main/resources/openapi/output-api.yaml src/main/resources/openapi/api

Generating the Output Project Run Maven in the root of the project to clean and install the project and run the CodeGen process for both Java Spring and TypeScript:

mvn clean install

This build will generate the backend Spring Boot service code under the generated/spring/ folder.

The generated project is a Maven Spring Boot project that provides the generated API via an executable jar.

You can build the executable jar and (optionally) run it using Maven.

cd generated/spring
# run with defaults (h2 db)
    --spring.datasource.url="$SPRING_DATASOURCE_URL" \
    --spring.jpa.hibernate.ddl-auto=update \
    --spring.datasource.username="$SPRING_DATASOURCE_USERNAME" \
    --spring.datasource.password="$SPRING_DATASOURCE_PASSWORD" \
    --spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver \
    --server.port="$SERVER_PORT" \
    --jwt.secret="$JWT_SECRET" \
|| error_exit "Failed to run backend instance"

THORAPI_SECRET_KEY is a MANDATORY environment or command line variable that is used to encrypt the SecureFields. Keep this private key secure.

A new THORAPI_SECRET_KEY can be generated with the generatekey command using the following command line:

java -jar lib/generator-<valkyrai_version>-exec.jar generatekey
export THORAPI_SECRET_KEY=generatedPrivateKey
// build the generated project
mvn clean install -f generated/spring/pom.xml